home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Leser 15 / Amiga Plus Leser CD 15.iso / Tools / Development / mmu / MuManual / Autodocs / mmuexternals.doc < prev    next >
Text File  |  2002-03-12  |  6KB  |  125 lines
  1.         External Setup Programs of the mmu.library
  2. ------------------------------------------------------------------------------
  3.  
  4. Abstract:
  5.  
  6. The mmu.library supports external tool programs that are run as part of
  7. the "MMU-Configuration" file, as for example the "P5Init" program. The 
  8. aim of this documentation is to explain this interface.
  9.  
  10.  
  11.  
  12. The "MMU-Configuration" contains commands that are used to setup the
  13. MMU tables when the system boots up. It gets executed by the mmu.library
  14. on startup, and modifies the preliminary MMU table setup that got
  15. constructed by the library before. The aim of this file is to allow the
  16. advanced user some fine tuning and optimizing of the MMU setup, and also
  17. to support exotic hardware that cannot be recognized by documented system
  18. mechanisms.
  19.  
  20. The MMU-Configuration file is a pure text file that can be edited by a 
  21. standard text editor like the system editor "Ed". The syntax of this file 
  22. is similar to that of a shell script and documented in [1]. 
  23.  
  24. When the mmu.library is parsing a line of the configuration file, it first 
  25. checks its for its internal commands. If no matching internal command 
  26. is found, the library looks for file of the same name in the "LIBS:mmu" 
  27. directory. This file is organized as a standard binary load file 
  28. (see [2]) and loaded by the LoadSeg() call of the dos.library. The file
  29. is however not executed in the sense of a standard shell command, if
  30. called from the shell, this file should not perform any action. Rather,
  31. the mmu.library scans the file for a "Resident structure" as documented
  32. in exec/resident.h [3],[4]. If the name of this resident structure is
  33. identically to that of the command within the MMU-Configuration file,
  34. the external command is accepted as valid. Otherwise it is rejected
  35. and an error message is generated.
  36.  
  37. The resident structure should indicate a type of NT_UNKNOWN, a
  38. version of at least 40 and a cleared rt_AutoInit flag.
  39.  
  40. Once the resident structure has been located, it is run by its rt_Init
  41. vector. The code is called with the following parameters:
  42.  
  43. a1    :    Register a1 contains a pointer to the MMUContext [5]
  44.         which is the object that should be manipulated by
  45.         the code by means of mmu.library calls.
  46.  
  47. a0    :    Register a0 contains a pointer to a struct RDArgs, ready
  48.         to be parsed by the dos.library ReadArgs() function.
  49.         ([2],[4])
  50.         This register should be used as third (d3) argument of
  51.         ReadArgs() to scan for optional command arguments.
  52.  
  53. a2    :    Register a2 contains the base of the dos.library system
  54.         library; hence, external commands need not to open the
  55.         dos.
  56.  
  57. a6    :    Register a6 contains the base of the mmu.library required
  58.         for all modifications of the context passed in a1.
  59.  
  60. It is very important that while in the external command, you *MUST NOT*
  61. OpenLibrary() the mmu.library; instead, use register a6 as base pointer.
  62. This is because your code is run as part of the mmu.library startup code
  63. in the context of the "ramlib" process. Trying an OpenLibrary() could
  64. start an endless loop or crash the system. 
  65.  
  66. The mmu.library is, at that point, not yet added to the system library 
  67. list, but is already constructed properly for operation. However, the
  68. MMU list encoded in the MMUContext you get as argument is not yet loaded
  69. into the MMU. Hence, you are still running under the boot configuration
  70. of the MMU; the mmu.library will load the MMU as soon as the startup
  71. code is finished, though.
  72.  
  73. The MMU context you receive as argument has already been modified by
  74. all the commands "above" your command in the MMU-Configuration, and
  75. may be touched by the commands below it before the mmu.library makes
  76. use of it.
  77.  
  78. It is *VERY IMPORTANT* to know that your code will be executed twice,
  79. because the MMU-Configuration file is also parsed twice. The library 
  80. will call you once with the "default MMUContext" in *a1, which is the
  81. context responsible for user mode accesses, and a second time with the
  82. "supervisor MMUContext", which will be used if the CPU is in supervisor
  83. mode [1],[6],[7]. Your code must be prepared to handle this, and to 
  84. make the proper modifications each time. Especially, if your code 
  85. requires to setup system resources, make sure you allocate/build these
  86. structures only once by checking for their existance before you use
  87. them. The mmu.library doesn't provide any mechanism to pass information
  88. from the first pass to the second, and your code is unloaded between
  89. the two calls.
  90.  
  91. Your code shall exit with a return code in d0. If this return code is
  92. zero, everything went well. A return code larger or equal than five
  93. will result in an error message; the mmu.library will then abort its
  94. setup process and will not be loaded into the system.
  95.  
  96. To avoid loading your code from the shell by accident, you should
  97. start the code by the following instruction sequence:
  98.  
  99.     moveq #-1,d0
  100.     rts
  101.  
  102. This will cause the shell to report an error should a user try to execute
  103. the file as a shell command. The Resident structure should start below
  104. this point.
  105.  
  106. ------------------------------------------------------------------------------
  107.  
  108. Literature:
  109.  
  110. [1]    :    The MMU.guide, MMULib.lha on Aminet.
  111. [2]    :    The AmigaDos Manual, Bantam Books, 3rd Ed.
  112. [3]    :    Amiga ROM Kernel Reference Manual: Includes and Autodocs
  113.         Addison Wesley Publishing Company, Inc, 1991,
  114.         ISBN 0-201-56773-3.
  115. [4]    :    Amiga ROM Kernel Reference Manual: Libraries
  116.         Addison Wesley Publishing Company, Inc, 1991,
  117.         ISBN 0-201-56774-1
  118. [5]    :    The mmu.library Programmer's Manual, MuManual.lha, on
  119.         Aminet.
  120. [6]    :    Programmer's Reference Manual,
  121.         Motorola document M68000PM/AD rev.1, Motorola 1992
  122. [7]    :    The M68000 Microprocessor Family, Yu-Cheng Liu,
  123.         Prentice-Hall International Editions, 1991
  124.         ISBN 0-13-553108-X
  125.